/**
   \file  lazebnik.hh
   \brief Implementation of the lazebnik algorithm.

   This file defines a class that encapsulates the details of the
   lazebnik algorithm.
*/

/*
   This file is part of libgist.

   libgist is free software; you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by the
   Free Software Foundation; either version 2 of the License, or (at your
   option) any later version.

   libgist is distributed in the hope that it will be useful, but WITHOUT
   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
   for more details.

   You should have received a copy of the GNU General Public License
   along with libgist; if not, write to the Free Software Foundation,
   Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
*/

/*
   REVISION HISTORY

   $HeadURL: http://libgist.googlecode.com/svn/branches/wu_dev/src/lazebnik.hh $
   $Id: lazebnik.hh 64 2011-09-18 03:40:31Z libgist@gmail.com $
*/

#ifndef LIBGIST_LAZEBNIK_DOT_HH
#define LIBGIST_LAZEBNIK_DOT_HH

//------------------------------ HEADERS --------------------------------

// Boost.GIL
#include <boost/gil/typedefs.hpp>
#include <boost/gil/image.hpp>

// Standard C++
#include <string>

//----------------------- NAMESPACE DEFINITION --------------------------

namespace gist {

//------------------------- CLASS DEFINITION ----------------------------

/**
   \brief Encapsulates the details of the lazebnik algorithm.

*/
class lazebnik {
   // All the implementation details are hidden in the lazebnik.cc file
   // behind an opaque object pointed to by this data member.
   void* p_impl ;

public:
   /// Initialization.
   lazebnik() ;

   /**
      \brief Collect training data.
      \param cat Image category.
      \param img Training image (grayscale).

      This method is meant to be called repeatedly in training mode. On
      each invocation, it will compute a grid of SIFT descriptors for the
      input training image (which should be a grayscale image) and
      accumulate this information in an internal data structure.

      For each training image, clients should specify the category to
      which it belongs. These category labels will be output during image
      classification.

      The method is thread-safe. Thus, clients may load training images
      in multiple threads and pass them to this function without having
      to worry about threading-related synchronization.
   */
   void data(const std::string& cat, const boost::gil::gray8_image_t& img) ;

   /**
      \brief Train the lazebnik algorithm.

      This method uses all the data collected by the lazebnik::data()
      function to obtain the vocabulary of prototypical SIFT descriptors
      as well as an SVM classifier that will help classify images into
      different categories.
   */
   void train() ;

   /**
      \brief Save vocabulary of SIFT descriptors.
      \param file_name Name of file in which vocabulary should be saved.

      This method saves the SIFT vocabulary obtained as a result of the
      training phase to the named file.
   */
   void save_vocabulary(const std::string& file_name) const ;

   /**
      \brief Save SVM classifier of SIFT descriptors.
      \param file_name Name of file in which classifier should be saved.

      This method saves the SVM classifier obtained as a result of the
      training phase to the named file.
   */
   void save_classifier(const std::string& file_name) const ;

   /// Clean-up.
   ~lazebnik() ;
} ;

//-----------------------------------------------------------------------

} // end of namespace encapsulating this file's definitions

#endif

/* So things look consistent in everyone's emacs... */
/* Local Variables: */
/* indent-tabs-mode: nil */
/* End: */

